Distinguish between private items and hidden items in rustdoc #67875
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document. This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.
dtolnay
added
the
T-rustdoc
|
Reassigning since QuietMisdreavus's status is "taking a break" and it looks like the recent PRs assigned to her in https://github.com/rust-lang/rust/pulls?q=is%3Apr+assignee%3AQuietMisdreavus+is%3Aclosed have all been reviewed by other people. |
|
Looks good to me, just a question: why moving |
|
It is not moved, it is deleted because I am intentionally overruling the decision from #46412. The old test was asserting @has for that case. My tests are asserting @!has. |
|
📌 Commit 90adafb has been approved by |
bors
added
the
S-waiting-on-bors
dtolnay
added
the
beta-nominated
|
Nominating for beta to avoid regressing #67851. |
Dylan-DPC-zz
pushed a commit
to Dylan-DPC-zz/rust
that referenced
this pull request
Jan 6, 2020
Distinguish between private items and hidden items in rustdoc I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document. This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another. Fixes rust-lang#67851. Closes rust-lang#60884.
Centril
added a commit
to Centril/rust
that referenced
this pull request
Jan 7, 2020
Distinguish between private items and hidden items in rustdoc I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document. This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another. Fixes rust-lang#67851. Closes rust-lang#60884.
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Jan 8, 2020
Distinguish between private items and hidden items in rustdoc I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document. This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another. Fixes rust-lang#67851. Closes rust-lang#60884.
bors
added a commit
that referenced
this pull request
Jan 8, 2020
Rollup of 10 pull requests Successful merges: - #67774 (Try statx for all linux-gnu target.) - #67781 (Move `is_min_const_fn` query to librustc_mir.) - #67798 (Remove wrong advice about spin locks from `spin_loop_hint` docs) - #67849 (Add a check for swapped words when we can't find an identifier) - #67875 (Distinguish between private items and hidden items in rustdoc) - #67887 (`Option::{expect,unwrap}` and `Result::{expect, expect_err, unwrap, unwrap_err}` have `#[track_caller]`) - #67955 (rustdoc: Remove more `#[doc(cfg(..))]` duplicates) - #67977 (Updates for VxWorks) - #67985 (Remove insignificant notes from CStr documentation) - #68003 (ci: fix wrong shared.sh import for publish_toolstate) Failed merges: - #67820 (Parse the syntax described in RFC 2632) - #67979 (Move `intravisit` => `rustc_hir` + misc cleanup) r? @ghost
bors
added a commit
that referenced
this pull request
Jan 8, 2020
Rollup of 10 pull requests Successful merges: - #67774 (Try statx for all linux-gnu target.) - #67781 (Move `is_min_const_fn` query to librustc_mir.) - #67798 (Remove wrong advice about spin locks from `spin_loop_hint` docs) - #67849 (Add a check for swapped words when we can't find an identifier) - #67875 (Distinguish between private items and hidden items in rustdoc) - #67887 (`Option::{expect,unwrap}` and `Result::{expect, expect_err, unwrap, unwrap_err}` have `#[track_caller]`) - #67955 (rustdoc: Remove more `#[doc(cfg(..))]` duplicates) - #67977 (Updates for VxWorks) - #67985 (Remove insignificant notes from CStr documentation) - #68003 (ci: fix wrong shared.sh import for publish_toolstate) Failed merges: - #67820 (Parse the syntax described in RFC 2632) - #67979 (Move `intravisit` => `rustc_hir` + misc cleanup) r? @ghost
Dylan-DPC-zz
pushed a commit
to Dylan-DPC-zz/rust
that referenced
this pull request
Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation `strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
Centril
added a commit
to Centril/rust
that referenced
this pull request
Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation `strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
Centril
added a commit
to Centril/rust
that referenced
this pull request
Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation `strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation `strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
JohnTitor
added a commit
to JohnTitor/rust
that referenced
this pull request
Jan 10, 2020
remove explicit strip-hidden pass from compiler doc generation `strip-hidden` is now implied by `--document-private-items` with rust-lang#67875, so there's no need to specify it anymore.
GuillaumeGomez
added
the
beta-accepted
ppannuto
added a commit
to tock/tock
that referenced
this pull request
Jan 20, 2020
As discussed in rust-lang/rust#67875, there is a difference between 'private' and 'hidden' items. Documenting private is now the default for **bin** crates, but we also want documentation for all of private library crates to be generated as well. Compare: - Before #1546: https://5e23ab06b4899600087c8c17--docs-tockosorg.netlify.com/nrf52/ficr/ - After #1546: https://deploy-preview-1546--docs-tockosorg.netlify.com/nrf52/ficr/ This restores our previous documentation
2 tasks
|
@dtolnay @GuillaumeGomez -- this patch does not backport cleanly onto beta, and the conflicts look like some code was shifted around. Can one of you prepare a commit targeting origin/beta? Thanks! (Note: beta promotion is scheduled for Monday next week). |
|
Sure thing, I can take care of it. |
|
Ah, actually, looks like I just needed to reformat librustdoc on beta. I forgot we had done that this cycle. |
Mark-Simulacrum
removed
the
beta-nominated
Merged
bors
added a commit
that referenced
this pull request
Jan 24, 2020
[beta] backports This backports: * Do not ICE on malformed suggestion spans #68256 * Distinguish between private items and hidden items in rustdoc #67875 * Revert parts of #66405. #67471 It also includes a few formatting commits to permit the backports to proceed cleanly (those are scoped to the relevant files, but still generate noise, of course). This was deemed easier than attempting to manually deal with the formatting. r? @ghost
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I believe rustdoc should not be conflating private items (visibility lower than
pub) and hidden items (attributedoc(hidden)). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document.This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.
Fixes #67851. Closes #60884.